home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / libdl / sgidladd.z / sgidladd
Encoding:
Text File  |  2002-10-03  |  8.4 KB  |  148 lines
  1. sgidladd(3c)                                           Last changed: 1-8-99
  2.  
  3.  
  4. NNAAMMEE
  5.      ssggiiddllaadddd - Opens a shared object and adds its variables to the name
  6.      space.
  7.  
  8. SSYYNNOOPPSSIISS
  9.      cccc [_f_l_a_g ...] _f_i_l_e ...  --llcc [_l_i_b_r_a_r_y ...]
  10.  
  11.      ##iinncclluuddee <<ddllffccnn..hh>>
  12.  
  13.      vvooiidd **ssggiiddllaadddd((ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, iinntt _m_o_d_e);
  14.  
  15. IIMMPPLLEEMMEENNTTAATTIIOONN
  16.      IRIX systems
  17.  
  18. DDEESSCCRRIIPPTTIIOONN
  19.      ssggiiddllaadddd is a facility for dynamically loading shared objects.  Unlike
  20.      ddllooppeenn(3) (without RRTTLLDD__GGLLOOBBAALL), the loaded shared object and all
  21.      associated dependent shared objects are added to the list of shared
  22.      objects just as if they had been specified at the time the program was
  23.      linked, or as if the __RRLLDD__LLIISSTT (see rrlldd(1)) environment variable had
  24.      been used.  That is to say, all of the names in the shared object
  25.      become available to satisfy references in shared objects during lazy
  26.      text resolution.  The DSOs are globally visible (see also the
  27.      "Namespace Issues" section in the ddllooppeenn(3c) man page).
  28.  
  29.      _m_o_d_e can be any one of RRTTLLDD__LLAAZZYY, RRTTLLDD__NNOOWW, or RRTTLLDD__NNOOWW__RREEPPOORRTT__EERRRROORR.
  30.  
  31.      RRTTLLDD__NNOOWW mode does exactly the same thing as RRTTLLDD__LLAAZZYY.  When the mode
  32.      is specified as RRTTLLDD__LLAAZZYY or RRTTLLDD__NNOOWW, resolution of all symbols is
  33.      performed, so that references that were previously unbound or bound to
  34.      weak symbols can be rebound to strong symbols.  However, unresolvable
  35.      function references (references to symbols that do not exist in any
  36.      shared object or in the mainline) are left dangling for further "lazy"
  37.      resolution, (possibly pending another call to ssggiiddllaadddd).
  38.  
  39.      When the mode is specified as RRTTLLDD__NNOOWW__RREEPPOORRTT__EERRRROORR, resolution of all
  40.      symbols is performed, and any unresolvable reference results in an
  41.      error return from ssggiiddllaadddd.  In this case, because resolution was not
  42.      completed, it is very dangerous to continue execution.  The main use
  43.      for this function is to ensure that at the point of ssggiiddllaadddd
  44.      execution, all symbols have been resolved. This facility is useful for
  45.      verifying completeness of interfaces.
  46.  
  47.      As with ddllooppeenn, a handle to the added object is returned. This handle
  48.      can be used to obtain addresses of specific symbols within the added
  49.      object.  This is somewhat less useful than with ddllooppeenn (without
  50.      RRTTLLDD__GGLLOOBBAALL), since in the case of ssggiiddllaadddd, rrlldd can resolve these
  51.      symbols directly (as can ddllooppeenn with RRTTLLDD__GGLLOOBBAALL).
  52.  
  53.      ssggiiddllaadddd is available in a library that is loaded if the --llcc option is
  54.      used with cccc, ff7777, or lldd.
  55.  
  56.    SSeeaarrcchhiinngg ffoorr SShhaarreedd OObbjjeeccttss
  57.      If other shared objects were link edited with _p_a_t_h_n_a_m_e when _p_a_t_h_n_a_m_e
  58.      was built, ddllooppeenn automatically loads those objects.  The directory
  59.      search path used to find both _p_a_t_h_n_a_m_e and the other needed objects is
  60.      the same as that used by rrlldd(1).  In particular, the search for
  61.      _p_a_t_h_n_a_m_e occurs in the following locations in the following order:
  62.  
  63.      1. The directory that _p_a_t_h_n_a_m_e specified if it is not a simple file
  64.         name (that is, it contains a // character).  In this case, the exact
  65.         file is the only location searched; steps two through four are
  66.         ignored.
  67.  
  68.      2. Any path specified by the --rrppaatthh argument to lldd(1) when the
  69.         executable file was statically linked.
  70.  
  71.      3. Any directory specified by the LLDD__LLIIBBRRAARRYY__PPAATTHH environment
  72.         variable.  This environment variable should contain a colon-
  73.         separated list of directories, in the same format as the PPAATTHH
  74.         variable (see sshh(1)).  64-bit programs examine the
  75.         LLDD__LLIIBBRRAARRYY6644__PPAATTHH variable, and if it is not set, they examine
  76.         LLDD__LLIIBBRRAARRYY__PPAATTHH.  New 32-bit ABI programs examine the
  77.         LLDD__LLIIBBRRAARRYYNN3322__PPAATTHH variable, and if it is not set, they examine
  78.         LLDD__LLIIBBRRAARRYY__PPAATTHH to determine whether an ABI-specific path has been
  79.         specified.
  80.         All three of these variables are ignored if the process is running
  81.         sseettuuiidd or sseettggiidd (see eexxeecc(2)).
  82.  
  83.      4. The default search paths are used.  These are //uussrr//lliibb:://lliibb for
  84.         32-bit programs, //uussrr//lliibb6644:://lliibb6644 for 64-bit programs, and
  85.         //uussrr//lliibb3322:://lliibb3322 for new 32-bit ABI programs.
  86.  
  87.      The __RRLLDD__RROOOOTT variable has its usual effect, as documented in the
  88.      manpage for rrlldd(1) (which means that for a sseettuuiidd or sseettggiidd program,
  89.      __RRLLDD__RROOOOTT is ignored).
  90.  
  91.      You can use ssggiiddllaadddd to open any number of times objects whose names
  92.      resolve to the same absolute or relative path name.  However, the
  93.      referenced object is loaded only once into the address space of the
  94.      current process.  The same object referenced by two different path
  95.      names, however, can be loaded multiple times.  For example, given the
  96.      object //uussrr//hhoommee//mmee//mmyylliibbss//mmyylliibb..ssoo, and assuming the current working
  97.      directory is //uussrr//hhoommee//mmee//wwoorrkkddiirr, the following code results in
  98.      mmyylliibb..ssoo being loaded twice for the current process:
  99.  
  100.           ...
  101.           void *handle1;
  102.           void *handle2;
  103.  
  104.           handle1 = sgidladd("../mylibs/mylib.so", RTLD_LAZY);
  105.           handle2 = sgidladd("/usr/home/me/mylibs/mylib.so", RTLD_LAZY);
  106.           ...
  107.  
  108.      On the other hand, given the same object and current working
  109.      directory, if you set LLDD__LLIIBBRRAARRYY__PPAATTHH equal to //uussrr//hhoommee//mmee//mmyylliibbss,
  110.      the following code results in mmyylliibb..ssoo being loaded only once.
  111.  
  112.           ...
  113.           void *handle1;
  114.           void *handle2;
  115.  
  116.           handle1 = sgidladd("mylib.so", RTLD_LAZY);
  117.           handle2 = sgidladd("/usr/home/me/mylibs/mylib.so", RTLD_LAZY);
  118.           ...
  119.  
  120. NNOOTTEESS
  121.      Use of ddllcclloossee on a DSO that has been added through use of ssggiiddllaadddd
  122.      can cause surprising side effects because ddllcclloossee forces many symbol's
  123.      GOT entries to be reset for re-lazy-evaluation.  A result of this is
  124.      that previously-saved (by the application or some library) function
  125.      pointers might hold values that could be obsolete or no longer
  126.      correct.
  127.  
  128.      Symbol lookups proceed in order on a linear list, and a DSO is not
  129.      opened twice with the same version number (unless different ddllooppeenn
  130.      paths make the DSO name appear different to _r_l_d).  When multiple
  131.      ssggiiddllaadddd commands are executed and an earlier DSO is closed by
  132.      ddllcclloossee, this can change the symbol to which a call is resolved.  For
  133.      more information, see the "Namespace Issues" section in the ddllooppeenn(3c)
  134.      man page.
  135.  
  136. RREETTUURRNN VVAALLUUEESS
  137.      If _p_a_t_h_n_a_m_e cannot be found, cannot be opened for reading, or is not a
  138.      shared object, or if an error occurs during the process of loading
  139.      _p_a_t_h_n_a_m_e or relocating its symbolic references, ssggiiddllaadddd returns NNUULLLL.
  140.      More detailed diagnostic information is available through the
  141.      ddlleerrrroorr(3c) man page.
  142.  
  143. SSEEEE AALLSSOO
  144.      ddllooppeenn(3) ddlleerrrroorr(3), ddllcclloossee(3), ddllssyymm(3), ssggiiddllooppeenn__vveerrssiioonn(3),
  145.      rrlldd(1), ddssoo(5)
  146.  
  147.      This man page is available only online.
  148.